<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta name="copyright" content=
"Copyright (c) IBM Corporation and others 2009, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Style-Type" content="text/css" />
<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" />
<title>Contributing a simple clean up and a simple save action using the
org.eclipse.jdt.ui.cleanUps extension point</title>

</head>
<body>
<h2>Contributing a Clean Up and a Save Action Using the <b>Clean Up</b> Extension Point</h2>

<p>The <a href=
"../reference/extension-points/org_eclipse_jdt_ui_cleanUps.html"><b>org.eclipse.jdt.ui.cleanUps</b></a>
extension point enables you to contribute your own Java code clean ups and Java editor save
actions. Clean ups help in resolving problems in a compilation unit or establishing a code style. A
save action is a special clean up that perform the requested modifications on save
automatically.</p>
<h3>Using the Extension Point</h3>
<p>To create a new extension for the <a href=
"../reference/extension-points/org_eclipse_jdt_ui_cleanUps.html"><b>org.eclipse.jdt.ui.cleanUps</b></a>
extension point you need to first provide the required extensions in the plugin.xml. There are 3
extensions that need to be declared as shown below with the example of a clean up which updates the
copyrights for a file on save:</p>
<pre>
   &lt;extension
         point="org.eclipse.jdt.ui.cleanUps"&gt;
      &lt;cleanUp
            id="org.eclipse.jdt.copyrightsaveaction.copyright_clean_up"
            class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightUpdaterCleanUp"&gt;
      &lt;/cleanUp&gt;
      
      &lt;cleanUpOptionsInitializer
            class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightOnSaveOptionsInitializer"
            cleanUpKind="saveAction"&gt;
      &lt;/cleanUpOptionsInitializer&gt;
      
      &lt;cleanUpConfigurationUI
            class="org.eclipse.jdt.ui.internal.copyrightupdater.CopyrightTabPage"
            name="%cleanUpConfigurationUI.name"
            cleanUpKind="saveAction"&gt;
      &lt;/cleanUpConfigurationUI&gt;
   &lt;/extension&gt;
</pre>

<p>For a description of the individual attributes, please refer to the extension point
documentation.</p>
<h3>Contributing a Clean Up</h3>
<p>To contribute a clean up, you need to first create the class that implements the <a href=
"../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUp.html"><b>ICleanUp</b></a> Interface. Lets
create the <code>CopyrightUpdaterCleanUp</code> class for our example clean up and implement the
inherited methods:</p>
<pre class="color1">
	public class CopyrightUpdaterCleanUp implements ICleanUp {

		private CleanUpOptions fOptions;
		private RefactoringStatus fStatus;

		public CopyrightUpdaterCleanUp() {
		}
	}
</pre>

The <code>CleanUpRequirements</code> contain various requirements for the clean up such as an AST
or a fresh AST containing changes from other clean ups, compiler options and changed regions, which
are used by the <code>CleanUpContext</code> to create the fix. It has to be returned from the
method getRequirements():
<pre class="color1">
	public CleanUpRequirements getRequirements() {
		boolean changedRegionsRequired= false;
		Map compilerOptions= null;
		boolean isUpdateCopyrights= fOptions.isEnabled("cleanup.update_copyrights");//$NON-NLS-1$
		return new CleanUpRequirements(isUpdateCopyrights, isUpdateCopyrights, changedRegionsRequired, compilerOptions);     
	}
</pre>
A human readable description should be returned for each step of the clean up that is enabled in
the current options:
<pre class="color1">
	public String[] getStepDescriptions() {
		if (fOptions.isEnabled("cleanup.update_copyrights"))//$NON-NLS-1$
			return new String[] {"Update Copyrights"};//$NON-NLS-1$

		return null;
	}
</pre>
The CleanUpOptions for the supported options keys will be set using setOptions(...):

<pre class="color1">
	public void setOptions(CleanUpOptions options) {
		Assert.isLegal(options != null);
		Assert.isTrue(fOptions == null);
		fOptions= options;  
	}
</pre>
The clean up pre-conditions and post-conditions are being checked in checkPreConditions(...) and
checkPostConditions(...):
<pre class="color1">
	public RefactoringStatus checkPreConditions(IJavaProject project, ICompilationUnit[] compilationUnits, IProgressMonitor monitor) throws CoreException {
		if (fOptions.isEnabled("cleanup.update_copyrights")) { //$NON-NLS-1$
			fStatus= new RefactoringStatus();
		}
		return new RefactoringStatus();
	}
</pre>
<pre class="color1">
	public RefactoringStatus checkPostConditions(IProgressMonitor monitor) throws CoreException {
		try {
			if (fStatus == null || fStatus.isOK()) {
				return new RefactoringStatus();
			} else {
				return fStatus;
			}
		} finally {
			fStatus= null;
		}
	}
</pre>
Finally, a <a href=
"../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpFix.html"><b>ICleanUpFix</b></a> is to be
created which fixes all the problems for the given context using createFix(...)

<pre class="color1">
	public ICleanUpFix createFix(CleanUpContext context) throws CoreException {
		CompilationUnit compilationUnit= context.getAST();
		if (compilationUnit == null)
			return null;

		return CopyrightsFix.createCleanUp(compilationUnit, fOptions.isEnabled("cleanup.update_copyrights"));//$NON-NLS-1$
	}
</pre>
<h3>Contributing a Clean Up Options Provider</h3>
<p>To create the UI for the clean up, an options provider tab page has to be created by
implementing the <a href=
"../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpConfigurationUI.html"><b>ICleanUpConfigurationUI</b></a>
interface. The page can be created by implementing the createContents(...) method in the
<code>CopyrightTabPage</code> class. The preferences page along with the desired groups and options
can be created using the method doCreatePreferences(). Optionally, a code snippet of the new clean
up with the given options can be shown in the clean up preview tab using the method getPreview().
If the CleanUpOptions get modified in the UI, they need to be set again using the method
setOptions(...).</p>
<h3>Contributing a Clean Up Options Initializer</h3>
<p>A clean up options initializer, which returns the default options for each clean up kind can be
created by implementing the <a href=
"../reference/api/org/eclipse/jdt/ui/cleanup/ICleanUpOptionsInitializer.html"><b>ICleanUpOptionsInitializer</b></a>.
The options initializer can either be contributed for a normal code clean up or for a save
action.</p>

<pre class="color1">
	public class CopyrightOnSaveOptionsInitializer implements ICleanUpOptionsInitializer {

		public CopyrightOnSaveOptionsInitializer() {
		}
</pre>
<p>The default options for this initializer can be set in setDefaultOptions(...)</p>
<pre class="color1">
	public void setDefaultOptions(CleanUpOptions options) {
		options.setOption("cleanup.update_copyrights", CleanUpOptions.TRUE);
	}
}
</pre>
<p>The UI code to configure the options for this example can be found here: <a href=
"CopyrightTabPage.html"><b>CleanUpTabPage.java</b></a>.</p>
</body>
</html>
